\name{IntData}
\alias{IntData}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Generate Interaction Data}
\description{
This function uses a model object (either directly supplied or created using the formula) to generate predicted values to "break down" an interaction (X * Z) by calculating the predicted values of Y across values of X at \emph{specific} values of Z.  It is meant to be used to generate a plot.  The default values of Z are +1 SD, mean, and -1 SD as is typical in psychology.
}
\usage{
IntData(object, data, x, intvar, intval, valname, continuous = "mean",
    discrete = "mode", n = 100L, FUN = "glm", ...)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{object}{\code{object} should either be a model object with methods for \code{\link{predict}} or a formula to be passed to the function specified in \code{FUN} (by default, \code{glm}).  If it is a model object, it should also include the actual data (this is normal for \code{lm} and \code{glm} but can be not included depending on arguments used to those functions.  It may not be typical for other model fitting functions or they may store the data in an unexpected place.).
}
  \item{data}{\code{data} is the dataset (only tested using data frames) to be used if \code{object} is a formula.  This is ignored if \code{object} is a model object.
}
  \item{x}{A character string indicating the variable to be plotted on the X axis.  The entire range of \code{x} is used in predicting values.
}
  \item{intvar}{A character string of the second interaction variable which only specific values are used in predicting values (equivalent to "Z" in the description).
}
  \item{intval}{\code{intval} specifies the values of the \code{intvar} to use in prediction (by default, +1 SD, the mean, and -1 SD).
}
  \item{valname}{A character string giving the names for use with \code{intval}.  This argument is ignored if \code{intval} is missing (defaulting to c("+1 SD", "Mean", "-1 SD")), but is required if \code{intval} is specified.
}
  \item{continuous}{A character string (defaults to "mean") indicating what value should be used for all numeric variables in the model that are not part of the interaction when calculating predicted values.  This argument is passed to the \code{\link{NormDF}} function which does al the actual work.  See its documentation for further options beyond "mean".
}
  \item{discrete}{A character string (defaults to "mode") indicating what value should be used for all discrete variables in the model that are not part of the interaction when calculating predicted values.  This argument is passed to the \code{\link{NormDF}} function which does al the actual work.  See its documentation for further options beyond "mode".
}
  \item{n}{\code{n} is the number of points to predict across the range of \code{x}.  It defaults to 100.  For most models, 2 is sufficient but where the interaction lines might curve (e.g., logistic models, or when there are powered terms in the model), more may be useful.
}
  \item{FUN}{\code{FUN} is a character string of the function name to be used to fit the model when \code{object} is a formula instead of a model object.  It defaults to "glm".
}
  \item{\dots}{\code{\dots} further arguments to be passed to \code{FUN}.  For example, \code{family = "binomial"} to fit logistic models.
}
}
\details{\code{IntData} was written to be used with the \pkg{ggplot2} package.  It has a \code{plot} method that uses \pkg{ggplot2}.  Currently, this is only meant to handle two-way interactions.  \code{x} must be a continuous variable, but \code{intvar} may be discrete so long as specific \code{intval}s are specified.  Future work should allow discrete variables for either variable and allow a more flexible treatment of them.

  For discrete predictors (logical or factors), the most frequent value is used for the prediction by default (i.e., the "mode").  For example if the variable was "Condition" coded as "Control = 0" and "Treatment = 1" for the model, if more units in the dataset recieved the control, then \code{IntData} would create the predictions using "Control", but if more units received the treatment, then \code{IntData} would create the predictions using "Treatment".  This is controlled by the \code{NormDF} function.  It may make more sense to always use the comparison 0 group rather than the most frequent, so this may change in a future release.

  \code{IntData} will also try to calculate and test the simple slopes if it can.  This currently uses the \code{\link{SimpleSlopes}} function which is still in development.
}
\value{
  A list of class "IntData" with attributes, "Variables" specifying the "x", "y", and "intvar" variable names in the data.
  \item{ModelData}{A data frame extracted from the model object used to generate the predicted values.}
  \item{PredictedData}{A data frame of the predicted values.  This will contain 3 variables.  One meant for the x axis, one for the y axis, and one for colour, linetype, or some other aesthetic to distinguish the different values of \code{intvar} used to "break down" the interaction.}
  \item{SS}{If the simple slopes could be calculated and tested, a list of the output from the \code{\link{SimpleSlopes}} function.  Otherwise \code{NULL}.
}}
\author{Joshua Wiley, \url{http://joshuawiley.com/}}
\note{Hopefully I will expand the notes and details soon.}
\seealso{\code{\link{plot.IntData}} for a plot method and \code{\link{summary.IntData}} for a summary.
}
\examples{
## Demonstration Setup
oldpar <- par(no.readonly = TRUE)
par(ask = TRUE)

mtcars <- mtcars
mtcars$cyl <- factor(mtcars$cyl)

## Fit and save predicted values for a simple linear model
ex.dat <- IntData(mpg ~ wt * hp, mtcars, x = "wt", intvar = "hp")
## Create the interaction plot
plot(ex.dat)

## Same model as before, but using non-defaults
ex.dat <- IntData(mpg ~ wt * hp, mtcars, x = "wt", intvar = "hp",
  intval = mtcars[c("Toyota Corolla", "Maserati Bora"), "hp"],
  valname = c("Corolla", "Maserati"))
## Create the interaction plot
plot(ex.dat)

## Fit a more complex linear model
ex.model <- lm(mpg ~ wt + hp * disp, mtcars)

## Using a model object instead of a formula and dataset
plot(IntData(ex.model, x = "hp", intvar = "disp"))

## Compare the effects of setting continuous to "zero"
plot(IntData(ex.model, x = "hp", intvar = "disp", continuous = "zero"))

## Create Fit a logistic model
ex.model <- glm(vs ~ mpg * hp, family = "binomial",
  data = mtcars)
## Demonstrate (perhaps nonsensically) using a logistic model
plot(IntData(ex.model, x = "mpg", intvar = "hp"))

## clean up
par(oldpar)
rm(ex.dat, ex.model, mtcars, oldpar)
}
\keyword{dplot}